Skip to content

do_arm: arago ActionHandler contract + action-ws lifecycle parity#121

Merged
AdaWorldAPI merged 3 commits into
mainfrom
claude/actionhandler-arago-parity
Jun 24, 2026
Merged

do_arm: arago ActionHandler contract + action-ws lifecycle parity#121
AdaWorldAPI merged 3 commits into
mainfrom
claude/actionhandler-arago-parity

Conversation

@AdaWorldAPI

Copy link
Copy Markdown
Owner

Goal

The operator's target: parity with arago's HIRO ActionHandler such that one "could basically switch from [arago's] Python to OGAR running it here." This PR scores OGAR against arago's actual implementation and closes the contract + lifecycle gap.

Grounded in the real arago sources (not just the vendored mirror): github.com/arago/ActionHandlers (config format), arago/python-hiro-stonebranch-actionhandler (a concrete daemon), and the HIRO 7 Action API action-ws protocol (the runtime contract).

The three parity findings

  1. Config + ontology are one contract — and OGAR lifts it. arago's handler YAML (Capability{Name,Description,Command,Parameter[]} + Applicability{ModelFilter,…}) and the OGIT NTO/Automation ontology (ActionHandler → provides → ActionApplicability → provides → ActionCapability) are two encodings of one shape. New do_arm::assemble_action_handler walks the vendored provides graph into ActionHandlerSpec / ApplicabilitySlot / CapabilitySlot / ActionParam — proven by assembles_the_full_action_handler_contract.
  2. ModelFilter is StateGuard. arago's node-match ModelFilter{Var,Mode,Value} maps field-for-field to OGAR KausalSpec::StateGuard{guard_field,guard_values} (the environmentFilter carrier).
  3. The action-ws lifecycle is the ActionInvocation Rubicon. submitAction → handler acknowledged → execute → sendActionResult → server acknowledged maps onto Pending → (commit_via: RBAC ∧ guard ∧ MUL) → Committed → Lance-append. timeout→state_timeout_millis, id→idempotency_key, result→resultParameters, server-ack→the CommitHook Lance commit. Nothing in the protocol needs a type OGAR lacks.

Verdict (docs/ARAGO-ACTIONHANDLER-PARITY.md scorecard)

OGAR is at full contract + lifecycle parity — every config / ontology / action-ws field has an OGAR type, and the execution gate (commit_via<ClassRbac>) is shipped. The switch to "OGAR running it here" reduces to two glue bricks over existing types, not new IR:

  • B1 — the ExecTarget executor (run the Command → result; graph-flow-action's trait, still no impl).
  • B2 — the action-ws adapter + deployed-handler-YAML → ActionDef/ActionParam instance lift.

Certified by PROBE-OGAR-ACTIONHANDLER-RUN: replay a real arago submitAction corpus through the adapter + executor; assert sendActionResult matches the Python handler's recorded result bit-for-bit.

Discipline

action_capability / intent / automation_issue stay reserved in the codebook — the assembly is string-keyed and doesn't resolve them by u16; they mint when B1 needs classid resolution (the "mint only what code uses" rule).

Tests

27 do_arm tests green (4 new: the contract assembly, the no-handler case, the ActionParam tuple), clippy-clean. Ledger D-ACTIONHANDLER-PARITY; board E-ARAGO-ACTIONHANDLER-PARITY.

Builds on main (the ConceptDomain::Automation mint, #120, already merged).

🤖 Generated with Claude Code


Generated by Claude Code

…pping

Brings OGAR to full CONTRACT + LIFECYCLE parity with arago's HIRO ActionHandler
(the operator's "switch from Python to OGAR running it here" goal), grounded in
the real arago sources (github.com/arago/ActionHandlers config format,
python-hiro-stonebranch-actionhandler daemon, HIRO 7 Action API action-ws
protocol) + the vendored OGIT NTO/Automation ontology.

do_arm additions (string-keyed; no new codebook mint needed):
- assemble_action_handler(entities) walks the OGIT `provides` graph
  (ActionHandler -> ActionApplicability -> ActionCapability) into
  ActionHandlerSpec / ApplicabilitySlot / CapabilitySlot.
- ActionParam { name, mandatory, default } — the arago Parameter I/O tuple.
- Parity points proven by tests: arago ModelFilter{Var,Mode,Value} ->
  KausalSpec::StateGuard (environmentFilter); Capability declares the
  mandatory/optional/result param slots (resultParameters = the output sig).

docs/ARAGO-ACTIONHANDLER-PARITY.md — the scorecard:
- config+ontology contract: full parity [G] (the assembly).
- action-ws protocol <-> ActionInvocation Rubicon lifecycle: submitAction ->
  ack -> execute -> sendActionResult -> ack maps onto Pending -> (commit_via:
  RBAC ^ guard ^ MUL) -> Committed -> Lance-append, field-for-field.
- the switch path: an OGAR action-ws adapter replaces the Python daemon; the
  only unbuilt pieces are B1 (the ExecTarget executor) and B2 (the action-ws
  adapter + deployed-YAML instance lift) — glue over existing types, not new IR.
- PROBE-OGAR-ACTIONHANDLER-RUN certifies B1/B2 (replay a real arago submitAction
  corpus; assert sendActionResult matches bit-for-bit).

27 do_arm tests green (4 new), clippy-clean. Ledger D-ACTIONHANDLER-PARITY;
EPIPHANIES E-ARAGO-ACTIONHANDLER-PARITY.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

claude added 2 commits June 24, 2026 06:33
The socket-free heart of the action-ws adapter (parity brick B2-core): the
typed protocol messages + the submitAction -> ActionInvocation ->
sendActionResult binding, no live WebSocket, no command execution. Builds on
the contract parity (#121); together they make the Python->OGAR switch a
transport/runner/parser job over existing types, not new IR.

crates/ogar-from-schema/src/action_ws.rs:
- SubmitAction / Acknowledged / SendActionResult — the typed action-ws messages
  (serde-gated for the wire).
- acknowledge(submit) — the 200 receipt.
- bind_parameters(supplied, ActionParam[]) — validates inputs against the
  capability signature (mandatory present, defaults filled) — the same check
  arago's Python handler runs before executing.
- submit_to_invocation(submit, def) — builds the Pending ActionInvocation
  (capability->predicate match, id->idempotency_key, host->object_instance,
  handler/scope->lokal); rejects capability mismatch.
- invocation_to_result(committed_inv, result) — only a Committed invocation
  (the Rubicon crossing) yields the sendActionResult.

7 new tests incl. full_action_ws_roundtrip (submit -> ack -> bind -> invoke ->
commit -> result, id-correlated). 34 do_arm/action_ws tests green under default
AND serde features; action_ws clippy-clean.

Docs: ARAGO-ACTIONHANDLER-PARITY scorecard updated (B2-core shipped; remaining
B1 executor + B2-transport live-WS + B2-lift YAML); D-ACTIONHANDLER-PARITY row.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP
…ocol core

Harvested the authoritative machine-readable contract from the HIRO 7.0 dev
portal (core.engine.datagroup.de/help/specs/definitions/{action-ws,action}.yaml)
and folded the corrections into the action-ws core, so it now matches the spec
rather than the tutorial-only first pass.

Corrections the spec forced:
- result is a SINGLE STRING (<= 1048576 chars), not an object: SendActionResult.result
  is now String; invocation_to_result JSON-encodes the bound resultParameters via
  a new minimal escaping json_object(); MAX_RESULT_LEN + ResultTooLarge guard.
- id is 12-256 chars: validate_id() + InvalidId.
- three missing message types added: NegativeAcknowledged {id,code,message},
  ConfigChanged (re-fetch capabilities), InboundError {code,message}.

New connection facts captured (for B2-transport):
- ACTION_WS_PATH = "/api/action-ws/1.0/connect"
- auth_subprotocol(token) = "token-$TOKEN" (the sec-websocket-protocol header)
- registration is REST (GET /capabilities, /applicabilities), NOT a WS handshake;
  configChanged just signals a re-fetch. The REST view lifts straight into
  do_arm::assemble_action_handler's ActionHandlerSpec (the B2-lift brick).

38 do_arm/action_ws tests green (4 new: nack, validate_id, json_object escaping,
auth_subprotocol) under default AND serde features; action_ws clippy-clean.

Docs: ARAGO-ACTIONHANDLER-PARITY §2a (the full harvested contract + the
corrections) + §6 spec URLs; D-ACTIONHANDLER-PARITY row updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP
@AdaWorldAPI AdaWorldAPI merged commit 9d524e2 into main Jun 24, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants